Introduction to MarkIt v03

Introduction

This is an introduction to the MarkIt markup language. MarkIt is a prototype of markup language made to balance leaks in the existing markup languages such as MarkDown¹ or ReST². MarkIt is developed with the Haskell³ programming language for a fast development and to enhance performance, reliability and portability.

The aim of MarkIt is to provide a common markup language to generate :

LaTeX documents
HTML web pages
Open document files (ODT).
Docx documents (possibly).

MarkIt can handle various of document formatting and structures such as :

Bullet lists.
Numbered lists.
Code snippets.
Quotations (experimental)
Comments
Figures.
Inlines images.

The basic way to use MarkIt is :

Write a text file in the MarkIt format with any text editor.
Read the file with the parser program to test it and detect some errors.
Generate the output file with a dedicated compiler for :
- HTML document.
- LaTeX .tex file to be compiled with pdflatex or xelatex.
- ODT OpenDocument readable with LibreOffice or MSOffice.
Standards kind of documents are provided for several usages:

Article /

to write a basic document

Report /

to write a more complex document containing several chapters, preambles, postambles and possibly annexes⁴.

Book /

to write a book.

Document structure

File Header

The file header is the very first part of a document.

The file header contains informations about the document creation. The common informations are :

Document title (Mandatory)
Name of the author (Mandatory)
Date of creation (Mandatory)
Keywords (Optional)
Docref (Optional)

It is separated from the content of the document by 3 dashes ---

The header of this document is defined like this :

---
title: Introduction to MarkIt v03
authors: Jean-Luc JOULIN
date : 2021/04/21
keywords:MarkIt, Presentation, LaTeX, Markdown, ReST, Markup, Math, Engineering
docref:introduction-to-markit-v03
---

Blocks

The document is made of blocks which provide a specific behaviour to the document separated by at least 1 blank line.

The main blocks are :

Text paragraphs
Lists
Titles and subtitles
Environments
Codeblocks
Quotations
Comments

Inlines

Inlines are the content of blocks and can be freely used inside of them. They provide functions to :

Modify the text styles.
- Bold font.
- Italic.
- Underlined.
- …
Make references to other elements.
- Link to websites.
- References to figures or titles.
- Bibliography.
Add inlines images.

Details of elements

Blocks elements

Blocks are the basics way to organize the code. Blocks are separated by 1 or more blanklines and have a different behaviour on the output.

Blocks are made of inlines (see bellow) and must be used with the same indentation.

Paragraphs

This is the basic block. It is composed by many lines of strings. This is a example of paragraphs:

Blocks are the basics way to organize the code.
Blocks are separated by 1 or more
blanklines and have a different behaviour
on the output.

Blocks are made of inlines (see bellow)
and must be used with the same indentation.

To begin another paragraph, leave 1 or more blanklines between two paragraphs.

Header blocks

The header blocks are used to structure the document by defining sections.

A header is defined by giving a title underlined by a serie of unique chars. According to the char, the level of the section is different.

Section
#######

Sub section
===========

Sub sub section
---------------

Sub sub sub section
^^^^^^^^^^^^^^^^^^^

At this time, only four level of section can be defined in a MarkIt file. This can be changed in the future.

Bullet list blocks

A bullet list can be produced by using a succession of asterisk (*) followed by a incremented list of block. The asterisk musn't be indented⁵.

The kind of bullet is set by the style of the document in the writing process and can't be changed by the user⁶.

This an example of bullet list :

* First element in the bullet list.

* Second element in the bullet list.
  More information about the element.
  
  More information.

Numbered list blocks

A numbered list can be produced by using a succession of sharps sign (#) followed by a incremented list of block. The sharps musn't be indented⁵.

The kind of numbering is set by the style of the document in the writing process and can't be changed by the user⁶.

This an example of numbered list :

# First element in the numbered list.

# Second element in the numbered list.
  More information about the element.
  
  More information.

Replacement blocks

Replacement block are used to describe a piece of document which can be called anywhere in the document by :

substitutions command :[identifier].

A replacement block begin with [identifier]: and is followed by an increment list of blocks. Here is an example of substitution block :

[identifier]:
  This is different from other markup languages
  where the asterisk must be indented.

Figure environment

The figure environment allow the user to place a picture inside the document with various options to tweak the final result. The allowable options are :

:width: :: allow the user to set the picture width.
:title: :: Set the figure title.
:ref: :: Set a reference to the figure.

The following code snippet is used to generate the figure bellow.

::figure
  :file: EPR-854x569.jpg
  :title: A photography of the EPR vessel in jpeg format (default width)
  :ref: firstfigure

::figure
  :file: IRSN-schema-cuve-EPR.png
  :title: A scheme of the EPR vessel in png format (width = 50% of line width)
  :ref: secondfigure
  :width: 50%

::figure
  :file: cuve-epr_image.jpg
  :title: Another photography of the EPR vessel in jpeg format (fixed width to 2 centimeter)
  :ref: anotherfigure
  :width: 2cm

Figure 1 : A photography of the EPR vessel in jpeg format (default width)

Figure 2 : A scheme of the EPR vessel in png format (width = 50% of line width)

Figure 3 : Another photography of the EPR vessel in jpeg format (fixed width to 2 centimeter)

MarkIt support these commons images format⁷ :

PNG For non destructives images (schemes, snapshots, …).
jpeg For photography.
eps will be available with some improvements.

Text Style (Inlines)

Bold text

The text can be written with a bold font by surrounding it with two asterisks ** like this **bold text**. It give the following result:

Normal text and some bold text

Emphasis

The text can be written with a emphasis font by surrounding it with one asterisks * like this *emphased text*. It give the following result:

Normal text and some emphased text

Underlined

The text can be underlined by surrounding it with two underscores _ like this __underlined text__. It give the following result:

Normal text and some underlined text

Strikeout

The text can be striked out by surrounding it with two tildes ~ like this ~~underlined text~~. It give the following result:

Normal text and ~~some striked out text~~

Underscript (indice)

The text can be written with a undercript font size by surrounding it with one underscore _ like this _underscript text_. It give the following result:

Normal text and _{some underscript text}

Superscript (exponent)

The text can be written with a superscript font size by surrounding it with one circumflex ^ like this ^superscript text^. It give the following result:

Normal text and ^{some superscript text}

External links

External links can be included with the command @[link](text). External links can be websites addresses or filepaths.

The text can handled all the text styles available.

This is some examples of links: Link to my personnal website and Another link to _my personnal website with markups

generated with the commands :

@[http://www.jeanjoux.fr/](Link to my personal website)

@[http://www.jeanjoux.fr/](Another *link* to _my_ **personal website** with markups)

References

It is possible to create a reference to some parts of the document with the command #[ref] and refere to it anywhere with @[ref]

Inlines images

An inline image can be included in a paragraph with the command ![]()

An inline image has its height fixed to the font size and cannot be changed. This is some examples of inline image.

These image have their height fixed because they are included in a text. A specific case of inlines image exist when they are in paragraph without any text. In this case image have their width adjusted to a given width proportionally to the number of images.

This is an example of this specific case:

generated with the command :


![thumb-up.png](thumb up picture)
![warning.png](warning symbol)
![radioactive2.png](radioactive symbol)

Note that inlines images can't be referenced and linked in the document. That's another difference with figures.

Footnotes

Footnotes can be included by using the command ^[footnote identifier]. Footnotes identifiers are uniques and are used to identify the footnote. The footnote must be described in a footnote block.

footnotes command ^[identifier].

If the footnote identifier is missing, an error is throw by the MarkIt parser

Fields

Fields can be used to place value inside a note. A field can contain only a string of char and is made to put a value inside a document⁸.

Fields are designed to be set outside the MarkIt file in another definition file.

If a field is not defined, it will be shown in the final doc as the field name surrounded by <$ and $>.

For an exemple the field $[field1] hold : <$field1$>

The field $[field2] hold : <$field2$>

The field $[field3] hold : <$field3$>

The field $[field4] is not defined : <$field4$>

Mathematic formulas

The main goal of MarkIt is to provide a standard support of mathematic formulas for scientific and engineering. Mathematic formulas can be written within $ using a specific language nearest from this used in Libre Office than LaTeX⁹.

Like images, math behaviour is different when written inside a paragraph or outside.

This is some inlines formulas $\frac{x^{2}}{a^{2}} + \frac{y^{2}}{b^{2}} = 1$ , $\sum_{a = 1}^{10} a = 55$ , $\int_{1}^{3} x^{2} d x$ and below some math formulas in block style.:

\frac{x^{2}}{a^{2}} + \frac{y^{2}}{b^{2}} = 1

\sum_{a = 1}^{10} a = 55

\int_{1}^{3} x^{2} d x = {[\frac{x^{3}}{3}]}_{1}^{3} = \frac{27}{3} - \frac{1}{3} = \frac{26}{3}

\int_{1}^{3} x^{2} d x

{cos}^{2} (α) + {sin}^{2} (α) = 1

$\vec{u} \land \vec{v} = (\begin{matrix} u_{2} v_{3} - u_{3} v_{2} \\ u_{3} v_{1} - u_{1} v_{3} \\ u_{1} v_{2} - u_{2} v_{1} \end{matrix})$

Arrays

A basic support for arrays is provided by MarkIt

Header 1	Header 2	Header 3	Header 4
Line 2	412.7	47235.45
Line 3	478.25	91.2	A very simple trigonometric math formula ${cos}^{2} (α) + {sin}^{2} (α) = 1$
Line 4	762.74	915.45	35.2

Header 1	Header 2	Header 3rv ervew vervw	Header 4
Line 2	412.7	47235.45
Line 3egg seg	478.25	91.2	A very simple trigonometric math formula ${cos}^{2} (α) + {sin}^{2} (α) = 1$
Line 4	762.74	915.45	35.2 ef zef ezg zgreg z

Notes

1.↑	Markdown is limited because it cannot handle array and internal links natively.
2.↑	ReST has no precise standard and reST is used by the Sphinx documentation tool and the docutils utilitie.
3.↑	Haskell is truly a very powerful programming language. It is reliable, efficient, strong and statically typed and even its logo is stylish. Have a look on its website to have more informations about Haskell.
4.↑	Not implemented yet!
5.↑	This is different from other markup languages where the asterisk must be indented.
6.↑	This is different from other markup language where the kind of bullet and numbering is set by the user (`*` for a bullet, `-` for a hyphen, `I.` for a roman numbering,…)
7.↑	This small number of format is due to some limitations with the output writers and the wish to homogenize the formatting of the documents. PDF images can be used with LaTeX but not with LibreOffice. wmf can be used with LibreOffice but can't be used by LaTeX. Many other image formats are obsolete or too fewly used.
8.↑	At this time, it is not possible to format fields to a specific format such as scientific/ingeneer notation. But this feature will be implemented soon.
9.↑	I assume that if you're ok to deal with LaTeX math formulation, you're ok to deal with the whole LaTeX environment directly and you don't need to use MarkIt